chrome.userScripts

Descrição

Use a API userScripts para executar scripts de usuário no contexto de scripts de usuário.

Permissões

userScripts

Para usar a API User Scripts, chrome.userScripts, adicione a permissão "userScripts" ao arquivo manifest.json e "host_permissions" para os sites em que você quer executar scripts.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

Disponibilidade

Chrome 120+ MV3+

Conceitos e uso

Um script do usuário é um snippet de código injetado em uma página da Web para modificar a aparência ou o comportamento dela. Ao contrário de outros recursos de extensão, como os scripts de conteúdo e a API chrome.scripting, a API User Scripts permite executar códigos arbitrários. Essa API é necessária para extensões que executam scripts fornecidos pelo usuário que não podem ser enviados como parte do pacote de extensão.

Ativar o uso da API userScripts

Depois que a extensão receber a permissão para usar a API userScripts, os usuários precisarão ativar uma chave específica para permitir que a extensão use a API. O interruptor específico necessário e o comportamento da API quando desativada variam de acordo com a versão do Chrome.

Use a verificação a seguir para determinar qual botão o usuário precisa ativar, por exemplo, durante a integração de novos usuários:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version > 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

As seções a seguir descrevem os diferentes botões e como ativá-los.

Versões do Chrome anteriores à 138 (alternar o modo de desenvolvedor)

Como desenvolvedor de extensões, você já tem o modo de desenvolvedor ativado na sua instalação do Chrome. Seus usuários também precisam ativar o modo de desenvolvedor.

Você pode copiar e colar as instruções a seguir na documentação da extensão para seus usuários.

  1. Acesse a página "Extensões" digitando chrome://extensions em uma nova guia. Os URLs chrome:// não podem ser vinculados.

  2. Ative o modo de desenvolvedor clicando no botão ao lado de Modo de desenvolvedor.

    Página "Extensions" do Chrome com o botão do modo de desenvolvedor destacado

    Página de extensões (chrome://extensions)

Chrome 138 e versões mais recentes (chave de ativação "Permitir scripts do usuário")

O botão Permitir scripts do usuário está na página de detalhes de cada extensão. Por exemplo, chrome://extensions/?id=YOUR_EXTENSION_ID.

Você pode copiar e colar as instruções a seguir na documentação da extensão para os usuários:

  1. Acesse a página "Extensões" digitando chrome://extensions em uma nova guia. Os URLs chrome:// não podem ser vinculados.
  2. Clique no botão "Detalhes" no card da extensão para conferir informações detalhadas sobre ela.
  3. Clique no botão ao lado de Permitir scripts do usuário.
O botão "Permitir scripts de usuário" na página de detalhes da extensão
Permitir a alternância de scripts de usuário (chrome://extensions/?id=abc...)

Verificar a disponibilidade da API

Recomendamos a verificação abaixo para determinar se a API userScripts está ativada, já que ela funciona em todas as versões do Chrome. Essa verificação tenta chamar um método chrome.userScripts() que sempre terá sucesso quando a API estiver disponível. Se essa chamada gerar um erro, a API não estará disponível:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    chrome.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

Trabalhar em mundos isolados

Os scripts de usuário e de conteúdo podem ser executados em um mundo isolado ou no mundo principal. Um mundo isolado é um ambiente de execução que não é acessível a uma página de destino ou outras extensões. Isso permite que um script do usuário mude o ambiente do JavaScript sem afetar a página de destino ou outros scripts de conteúdo e de usuário das extensões. Por outro lado, os scripts do usuário (e de conteúdo) não são visíveis para a página de host ou para os scripts do usuário e de conteúdo de outras extensões. Os scripts executados no mundo principal são acessíveis e ficam visíveis para as páginas de destino e outras extensões. Para selecionar o mundo, transmita "USER_SCRIPT" ou "MAIN" ao chamar userScripts.register().

Para configurar uma política de segurança de conteúdo para o mundo USER_SCRIPT, chame userScripts.configureWorld():

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

Mensagens

Assim como os scripts de conteúdo e os documentos fora da tela, os scripts do usuário se comunicam com outras partes de uma extensão usando mensagens, ou seja, eles podem chamar runtime.sendMessage() e runtime.connect() como qualquer outra parte de uma extensão. No entanto, eles são recebidos usando manipuladores de eventos dedicados, ou seja, eles não usam onMessage ou onConnect. Esses manipuladores são chamados de runtime.onUserScriptMessage e runtime.onUserScriptConnect. Os processadores dedicados facilitam a identificação de mensagens de scripts do usuário, que são um contexto menos confiável.

Antes de enviar uma mensagem, chame configureWorld() com o argumento messaging definido como true. Os argumentos csp e messaging podem ser transmitidos ao mesmo tempo.

chrome.userScripts.configureWorld({
  messaging: true
});

Atualizações de extensões

Os scripts do usuário são limpos quando uma extensão é atualizada. Para adicionar de volta, execute o código no gerenciador de eventos runtime.onInstalled no worker de serviço da extensão. Responda apenas ao motivo "update" transmitido para o callback de evento.

Exemplo

Este exemplo é do exemplo de userScript no nosso repositório de exemplos.

Registrar um script

O exemplo a seguir mostra uma chamada básica para register(). O primeiro argumento é uma matriz de objetos que define os scripts a serem registrados. Há mais opções do que as mostradas aqui.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

Tipos

ExecutionWorld

O mundo do JavaScript para um script do usuário ser executado.

Enumeração

"MAIN"
especifica o ambiente de execução do DOM, que é o ambiente de execução compartilhado com o JavaScript da página host.

"USER_SCRIPT"
especifica o ambiente de execução específico para scripts do usuário e está isento do CSP da página.

InjectionResult

Chrome 135 e versões mais recentes

Propriedades

  • documentId

    string

    O documento associado à injeção.

  • erro

    string opcional

    O erro, se houver. error e result são mutuamente exclusivos.

  • frameId

    número

    O frame associado à injeção.

  • resultado

    qualquer opcional

    O resultado da execução do script.

InjectionTarget

Chrome 135 e versões mais recentes

Propriedades

  • allFrames

    booleano opcional

    Define se o script precisa ser injetado em todos os frames da guia. O padrão é "false". Isso não pode ser verdadeiro se frameIds for especificado.

  • documentIds

    string[] opcional

    Os IDs de documentIds específicos para injetar. Não precisa ser definido se frameIds estiver definido.

  • frameIds

    number[] opcional

    Os IDs dos frames específicos para injetar.

  • tabId

    número

    O ID da guia em que será feita a injeção.

RegisteredUserScript

Propriedades

  • allFrames

    booleano opcional

    Se for verdadeiro, ele será injetado em todos os frames, mesmo que não seja o principal na guia. Cada frame é verificado de forma independente para requisitos de URL. Ele não será injetado em frames filhos se os requisitos de URL não forem atendidos. O padrão é "false", o que significa que apenas o frame superior é correspondente.

  • excludeGlobs

    string[] opcional

    Especifica padrões de curinga para páginas em que este script de usuário NÃO será injetado.

  • excludeMatches

    string[] opcional

    Exclui páginas em que esse script de usuário seria injetado. Consulte Padrões de correspondência para mais detalhes sobre a sintaxe dessas strings.

  • ID

    string

    O ID do script do usuário especificado na chamada de API. Essa propriedade não pode começar com "_", porque ele é reservado como um prefixo para IDs de script gerados.

  • includeGlobs

    string[] opcional

    Especifica padrões de curinga para as páginas em que esse script do usuário será injetado.

  • js

    ScriptSource[] opcional

    A lista de objetos ScriptSource que definem as origens dos scripts a serem injetados nas páginas correspondentes. Essa propriedade precisa ser especificada para ${ref:register} e, quando especificada, precisa ser uma matriz não vazia.

  • correspondências

    string[] opcional

    Especifica em quais páginas esse script do usuário será injetado. Consulte Padrões de correspondência para mais detalhes sobre a sintaxe dessas strings. Essa propriedade precisa ser especificada para ${ref:register}.

  • runAt

    RunAt opcional

    Especifica quando os arquivos JavaScript são injetados na página da Web. O valor preferencial e padrão é document_idle.

  • mundo

    ExecutionWorld opcional

    O ambiente de execução do JavaScript em que o script será executado. O padrão é `USER_SCRIPT`.

  • worldId

    string opcional

    Chrome 133 e versões mais recentes

    Especifica o ID do mundo do script do usuário em que será executado. Se omitido, o script será executado no mundo padrão do script do usuário. Válido apenas se world for omitido ou for USER_SCRIPT. Os valores com sublinhados iniciais (_) são reservados.

ScriptSource

Propriedades

  • código

    string opcional

    Uma string que contém o código JavaScript a ser injetado. É preciso especificar exatamente um entre file ou code.

  • arquivo

    string opcional

    O caminho do arquivo JavaScript a ser injetado em relação ao diretório raiz da extensão. É preciso especificar exatamente um entre file ou code.

UserScriptFilter

Propriedades

  • ids

    string[] opcional

    getScripts só retorna scripts com os IDs especificados nesta lista.

UserScriptInjection

Chrome 135 e versões mais recentes

Propriedades

  • injectImmediately

    booleano opcional

    Se a injeção precisa ser acionada no destino o mais rápido possível. Isso não garante que a injeção ocorra antes do carregamento da página, porque ela pode já ter sido carregada quando o script atinge o destino.

  • A lista de objetos ScriptSource que definem as origens dos scripts a serem injetados no destino.

  • Detalhes que especificam o destino em que o script será injetado.

  • mundo

    ExecutionWorld opcional

    O "mundo" do JavaScript em que o script será executado. O padrão é USER_SCRIPT.

  • worldId

    string opcional

    Especifica o ID do mundo do script do usuário em que será executado. Se omitido, o script será executado no mundo padrão do script do usuário. Válido apenas se world for omitido ou for USER_SCRIPT. Os valores com sublinhados iniciais (_) são reservados.

WorldProperties

Propriedades

  • csp

    string opcional

    Especifica o csp do mundo. O padrão é o csp `ISOLATED` do mundo.

  • mensagens

    booleano opcional

    Especifica se as APIs de mensagens estão expostas. O padrão é false.

  • worldId

    string opcional

    Chrome 133 e versões mais recentes

    Especifica o ID do mundo do script do usuário específico a ser atualizado. Se não for fornecido, atualiza as propriedades do mundo do script de usuário padrão. Os valores com sublinhados iniciais (_) são reservados.

Métodos

configureWorld()

Promessa 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Configura o ambiente de execução `USER_SCRIPT`.

Parâmetros

  • properties

    WorldProperties

    Contém a configuração do mundo do script do usuário.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

execute()

Promessa Chrome 135+ 
chrome.userScripts.execute(
  injection: UserScriptInjection,
  callback?: function,
)

Injeta um script em um contexto de destino. Por padrão, o script será executado em document_idle ou imediatamente se a página já tiver sido carregada. Se a propriedade injectImmediately estiver definida, o script será injetado sem espera, mesmo que a página não tenha terminado de carregar. Se o script for avaliado como uma promessa, o navegador vai aguardar a promessa ser resolvida e retornar o valor resultante.

Parâmetros

Retorna

  • Promise<InjectionResult[]>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getScripts()

Promessa 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

Retorna todos os scripts de usuário registrados dinamicamente para essa extensão.

Parâmetros

Retorna

  • As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getWorldConfigurations()

Promessa Chrome 133 e mais recentes 
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

Recupera todas as configurações de mundo registradas.

Parâmetros

Retorna

  • Promise<WorldProperties[]>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

register()

Promessa 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Registra um ou mais scripts do usuário para essa extensão.

Parâmetros

  • Contém uma lista de scripts do usuário a serem registrados.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

resetWorldConfiguration()

Promessa Chrome 133+ 
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

Redefine a configuração de um mundo de script do usuário. Todos os scripts injetados no mundo com o ID especificado vão usar a configuração padrão do mundo.

Parâmetros

  • worldId

    string opcional

    O ID do mundo do script do usuário a ser redefinido. Se omitido, redefine a configuração do mundo padrão.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

unregister()

Promessa 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

Cancela o registro de todos os scripts de usuário registrados dinamicamente para essa extensão.

Parâmetros

  • filtrar

    UserScriptFilter opcional

    Se especificado, esse método desregistra apenas os scripts do usuário que correspondem a ele.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

update()

Promessa 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Atualiza um ou mais scripts de usuário para essa extensão.

Parâmetros

  • Contém uma lista de scripts do usuário a serem atualizados. Uma propriedade só será atualizada para o script atual se for especificada nesse objeto. Se houver erros durante a análise de script/validação de arquivo ou se os IDs especificados não corresponderem a um script totalmente registrado, nenhum script será atualizado.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    () => void

Retorna

  • Promise<void>

    As promessas têm suporte no Manifest V3 e versões mais recentes, mas os callbacks são fornecidos para compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.